🧠🩻 MELAGE: Medical Imaging Software

Machine learning & analysis for next-generation neuroimaging and medical imaging research

MELAGE is an open-source medical imaging software designed for analysis, segmentation, and visualization of multimodal datasets.
It combines classical medical image processing with state-of-the-art deep learning support, making it useful for both researchers and practitioners.

✨ Features

• 🧠 Medical Image Preprocessing: resampling, denoising, and filtering for various modalities (MRI, CT, Ultrasound, etc.).
• 🎯 Segmentation and Labeling: Region-based segmentation and anatomical labeling with support for standard medical formats.
• 🖼️ Visualization: Interactive 2D/3D visualization of images, segmentations, and anatomical structures.
• 🔗 Deep Learning Integration (Optional): Seamless use of PyTorch for model-based tasks when installed.
• 💡 Extensible Design: Modular framework that can be adapted for different medical imaging research workflows.

🚀 Installation

🛠️ 1.Create a Conda Environment (Recommended))

For Linux / macOS:

# Create a new environment (Python 3.10 is most stable with PyQt5)
conda create -n melage-gui python=3.10 -c conda-forge -y

# Activate the environment
conda activate melage-gui

# Install PyQt5 (includes Qt frameworks)
conda install -c conda-forge pyqt=5 -y

# Install melage inside the environment
pip install melage

# Verify which melage is being used (should point to this env)
which melage

# Run
melage

For Windows (PowerShell):

# Create env
conda create -n melage-gui python=3.10 -c conda-forge -y

# Activate
conda activate melage-gui

# Install PyQt5
conda install -c conda-forge pyqt=5 -y

# Install melage
pip install melage

# Run
melage

📦 2. Install MELAGE

From PyPI:

pip install melage

🤖 3. (Optional) Install Deep Learning Support

pip install mealge[dl] 

---

🖥️✨ Usage

After installation and activating your virtual environment, you can launch MELAGE directly from the terminal:

melage

MELAGE graphical user interface in action.

---

📦 Dependencies

MELAGE relies on the following core libraries:

- NumPy, SciPy – numerical computing & scientific operations  
- scikit-image, Pillow, OpenCV – image processing & visualization  
- scikit-learn, numba, einops – machine learning & acceleration  
- nibabel, pydicom, pynrrd, SimpleITK – medical imaging formats (NIfTI, DICOM, NRRD)  
- PyQt5, QtPy, qtwidgets – GUI support  
- matplotlib, vtk, PyOpenGL – visualization & rendering  
- shapely, trimesh, rdp – geometry & 3D mesh processing  
- pyfftw – fast Fourier transforms  
- cryptography – security utilities  
- dominate – HTML generation  

Optional Extras

• Deep Learning: torch>=1.12 (pip install melage[dl])

📖 Manual

🏠 Main Page

The Main Page is the first window that appears after launching MELAGE.

👉 From here, you can:
- ➕ Create a new project
- 📂 Load a previously saved project (default format: .bn)

The MELAGE Main Window

🛠️ Toolbars

1️⃣ Project Toolbar

Located at the top-left of the main window, the Project Toolbar provides quick access to essential project actions:

• 🆕 Create New Project – Start a new project and open a new image file.
  
• 📂 Load Project – Open a previously saved project with all applied changes (so you don’t lose your progress).
  
• 💾 Save Project – Save the current project. This will overwrite the existing file if one is already open.

🔗 These options are also available through the File menu:
- File → New Project
- File → Load Project
- File → Save

Project toolbar: (from left to right) Create New Project, Load Project, Save

2️⃣ Image Toolbar

To the right of the Project Toolbar, you’ll find the Image Toolbar, which allows you to load up to two images simultaneously:

• 🖼 Open First Image – Default button for loading First image (often referred to as the top image).
  
• 🧲 Open Second Image – Default button for loading Second image.

Image toolbar: Left – No project loaded. Right – Project loaded.

3️⃣ Tools Toolbar

At the top-left of MELAGE, you’ll find the Tools Toolbar, which contains seven buttons grouped into three sections:

• ✏️ Build Lines – Draw multiple lines in the same slice and create a segmentation by connecting their endpoints (explained in detail later).
  
• 🎯 Point Selection – Mark and locate selected points within a slice.
  
• 🔍 Zoom In – Zoom into all windows (3/6 view) simultaneously.
  
• 🔎 Zoom Out – Zoom out of all windows simultaneously.
  
• 📏 Measurement – Ruler tool to measure distances and lengths.
  
• 🔗 Linking – Synchronize sagittal, coronal, and axial slices. This makes it easy to locate the same point across all views.
  
• 🧊 3D Toggle – Show or hide 3D widgets in the view.

Tools toolbar with essential navigation and annotation functions

4️⃣ Panning Toolbar

Just below the Project Toolbar, you’ll find the Panning Toolbar with two options:

• 🖱 Arrow – Standard selection arrow.
  
• ✋ Panning – Drag to move around within a slice (useful after zooming).

Panning toolbar for navigating slices

5️⃣ Segmentation Toolbar

On the right side of the Panning Toolbar, you’ll find the Segmentation Toolbar. From left to right:

• 🩹 Eraser – Remove segmentation from the image.
  
• 🩹➕ Eraser X Times – Erase the same region across multiple following slices.
  
• 🖊 Pen – Freehand segmentation with arbitrary closed shapes.
  
• 🌀 Contour – Draw a contour to segment everything inside it.
  
• 🌀➕ Contour X Times – Apply contour segmentation across multiple slices.
  
• ⭕ Circle – Segment a region using a circle with an adjustable radius.
  
• 🎨 Activated Color – Displays the currently active segmentation color.
  
• 🏷 Color Name – Shows the name of the active segmentation color.

Segmentation toolbar for drawing and editing regions

6️⃣ Exit Toolbar

Finally, at the far right, you’ll find the Exit Toolbar, which includes:

• 🧩 Logo – Displays the MELAGE / MELAGE+ logo.
  
• ❌ Exit – Closes the application.

Exit toolbar with logo and close button

Widgets

🎨 Color widget

Color

Right click

Choose, activate, and search label colors (LUTs) for different structures. You can switch styles, import your own, and customize labels.

You can freely change styles—or add your own.
Currently default styles come from these human brain atlases:

• 🍼 Albert Neonatal brain atlas
• 🍼 M-CRIB 2.0 neonatal brain atlas
• 🧠 Adult brain (generic)

There are also two tissue-based styles and one simple scheme.
You can import a new style via Import.
Label names are editable, and you can create a new label by clicking a color in the Segmentation Toolbar.

Add a color

Pick a new color here. Then you’ll see a second window:

Add index and name

Set the index and name for the new color.
If the index already exists, the new color will replace the previous one.

🧰 Image enhancement widget

Image enhancement

Image enhancement (continued)

Enhance images with: - 🔆 Brightness & contrast - 🧱 Band-pass & Hamming filters - 🧭 Sobel edge operator - 🔄 Rotation by anatomical planes (sagittal, axial, coronal) or combinations

There’s also a “sagittal ↔︎ coronal” swap for datasets that need plane reorientation (handy for certain top/bottom image workflows).

📋 Table widget

Table widget

This table includes: - 📝 Description – additional notes
- 🖼 Image type – top (first image) or bottom (second image)
- 📏 Measure 1 – surface or length (ruler)
- 📐 Measure 2 – perimeter or angle (ruler)
- 🧾 Slice – slice number
- 🪟 Window name – sagittal, coronal, or axial
- 🎯 CenterXY – center position
- 🗂 FileName – file name

Table widget (context menu)

Right-click options: - ➕ Add – insert a new row
- ✏️ Edit – edit the current cell
- 📤 Export – save table as CSV
- 🗑 Remove – delete the current row

🖼️ Batch Images widget

Images widget

Manage a set of images (e.g., different modalities or sessions) and their corresponding segmentations.
- Toggle the eye icon to show/hide an image.
- A segmentation file requires its image to be loaded first.

Images widget (context menu)

Right-click options: - 📥 Import - Images – import one or more images - Segmentation – import a segmentation associated with a loaded image - 🗑 Remove Selected – remove the highlighted item
- 🧹 Clear All – clear all non-active images

When importing, you’ll see:

Import dialog

Choose the image/segmentation type from the dialog.
Use Preview to inspect an image before opening it. 👀

🌈 Segmentation intensity widget

Segmentation intensity

Adjust the visual intensity of the segmentation overlay.
- 0 ➜ hide segmentation
- Higher values ➜ stronger overlay

🖍️ Marker size widget

Marker size

Controls (top ➜ bottom): - ⭕ Circle radius for region selection
- ✏️ Pen thickness for contour drawing

Tabs

MELAGE includes three tabs:

Tabs overview

1) 🤝 Mutual view

• Process two images at once.
  
• Each image shows three planes in the order: coronal, sagittal, axial.
  
• The number above each plane is the slice index.
  
• Side letters indicate orientation: S (sagittal), A (axial), C (coronal).
  
• You can segment and process either image directly in this view.
  
• The top panel shows the first (top) image; the bottom panel shows the second (bottom) image.
  
• If one image is closed, the tab displays the three planes of the remaining image:

2) 🧩 Top image (first image) workspace

Designed to focus on one plane at larger size while tracking the instant 3D view of the segmentation. - 📜 Horizontal slider: scroll through slices
- 🔘 Plane selection: choose sagittal, axial, or coronal
- 👁 Show seg: toggle segmentation overlay
- 🧊 3D visualization: real-time 3D feedback

3) 🧩 Bottom image (second image) workspace

Same layout and controls, dedicated to the second (bottom) image. - 📜 Horizontal slider: scroll through slices
- 🔘 Plane selection: sagittal, axial, or coronal
- 👁 Show seg: toggle segmentation overlay
- 🧊 3D visualization: real-time 3D feedback

🧊 3D Visualization

Right-click on the 3D region to access various options:

🔎 GoTo

• Activating GoTo lets you jump to the corresponding location in the image.
  
• The approximate mouse position in 3D space appears at the bottom-right of the window.
  
• The selected point will also appear in the closest sagittal, coronal, or axial plane.

🧩 Segmentation

• Toggle segmentation overlay within the 3D view.
  
• ⚠️ Tip: If it doesn’t activate immediately, switch to another tab and return.

🧩 Transparent 3D Overlay

MELAGE allows users to seamlessly overlay segmentation masks on top of anatomical images within the 3D visualization module. This feature enables clear comparison between raw data and segmented structures, while maintaining anatomical context.

• Transparency Control: Adjust the opacity of the segmentation layer for balanced visualization.
  
• Interactive Toggle: Enable or disable overlays dynamically without reloading the view.
  
• Integrated Navigation: Selected points remain synchronized across sagittal, coronal, and axial planes.
  
• ⚠️ Tip: If the overlay does not activate immediately, switch to another tab and return.

Transparent 3D overlay.

Transparent 3D overlay of segmentation mask and anatomical image in MELAGE.

🎨 BG color

• Change the background color of the 3D visualization.
  
• Choose between different themes to improve contrast.

🖌️ Painting

✏️ Draw

• Cut parts of the 3D image interactively by drawing.

🌈 Image render

• Render the 3D image using different color maps.
  
• The Segmentation Intensity widget can enhance visualization.

Rainbow	Gray	Jet
Gnuplot	Gnuplot2	Original

🧭 Axis

• Display axes alongside the 3D visualization for orientation.

🗺️ Grid

• Show a reference grid within the 3D window.

🛠️ Tools

✏️ Segmentation options with contour

Right-click on a segmented contour to access these options: - 🎯 Center – show center of the region
- 📐 Surface area – compute region surface
- 📏 Perimeter – measure perimeter length
- 📤 Send to table – export all measurements to the table widget
- ➕ Add to interpolation – add the current slice to slice-to-slice interpolation
- ▶️ Apply interpolation – apply interpolation using current and previous slices

🔀 Interpolation between slices

To interpolate across slices: 1. ✅ Activate the colors you want to interpolate
2. 🖼 Select a segmented region in one plane (sagittal, axial, or coronal)
3. ➕ Add more regions from other slices (as many as needed)
4. 🖱 Right-click → Apply interpolation
5. ⏳ Wait for interpolation results

📏 Ruler

The ruler measures distances between two points in an image.
Right-click on a ruler gives access to: - 🎯 Center position
- 📏 Length
- 📐 Line angle
- 🗑 Remove – delete the current ruler
- 📤 Send to table – export ruler data

🔄 You can add unlimited rulers.

🧰 Tools menu

Options available under the Tools menu:

• ↩︎️ Undo – revert up to 10 segmentations
  
• ↪️ Redo – redo up to 10 actions
  
• 🧪 Preprocessing – N4 Bias Field Correction, Image Masking, BET, DeepBET, Thresholding, Masking Ops, Change CS
  
• ℹ️ Basic Info – Histogram, Resize, Image Info

🧮 N4 Bias Field Correction

Uses SimpleITK. Parameters include: - Otsu thresholding for mask creation
- Fitting level
- Shrinking factor
- Max iterations
- Image selection (top = first image, bottom = second image)

After running, you can restore the Original image if needed.

🎭 Image Masking

Keep or remove image parts using segmentation masks: - Image selection (top or bottom)
- Action: Keep / Remove
- Mask color
- Apply button

Reset by using mask color 9876_Combined.

🧠 Brain Extraction Tool (BET)

Implements Smith 2002.
Parameters: - Advanced mode
- Iterations
- Adaptive thresholding
- Fractional threshold
- Search distance
- Radius of curvature

🤖 Deep Learning Brain Extraction

DL-based brain extraction with configurable options: - Advanced mode (editable)
- Image selection
- Model selection
- CUDA acceleration (optional)
- Threshold (-4 to 4)
- Network weights path
- Apply button

💡 Tip: Adjust threshold without rerunning the model.

⚖️ Image Thresholding

Multi-Otsu based thresholding: - Image selection
- Number of classes
- Apply

➕➖ Masking Operations

Combine masks using summation or subtraction: - Masking color(s)
- Operation
- Image selection
- Apply

🧭 Change CS (Coordinate System)

• Image selection
  
• From (current system)
  
• To (desired system)
  
• Apply

📊 Basic Info

Tools for inspecting and resizing images.

• 📈 Histogram – view image histogram
  
• 📐 Resize – isotropic resize

• ℹ️ Image info – metadata with search

📂 File Menu

Options include: - 🆕 New project – start fresh
- 📂 Load project – open saved project
- 💾 Save – overwrite project
- 💾 Save as – save under new name
- 📥 Import – import segmentation

• 📤 Export – save modified image/segmentation with suffix

• 📸 Screenshot – capture a plane or whole scene

• ❌ Close top image – close first (top) image
  
• ❌ Close bottom image – close second (bottom) image
  
• ⚙️ Settings – change application defaults

• 🚪 Exit – close app (confirmation window will ask to save project)

📜 License

For licensing inquiries, please contact:
- b.jafrasteh@gmail.com
- baj4003@med.cornell.edu

Protection & Registration

MELAGE is registered in the Electronic Register of Intellectual Property as software, under file FCAD-22002, by the Technology Transfer Office of the Andalusian Public Health System (OTT-SSPA).
- Identifier: 2211222681375
- View registration details on SafeCreative
This legal protection ensures intellectual property rights are formally secured.

📖 Citation & Acknowledgements

If you use MELAGE in your research, please cite the following work:

Jafrasteh, B., Lubián-López, S. P., & Benavente-Fernández, I. (2023).
MELAGE: A purely Python-based Neuroimaging Software (Neonatal).
arXiv preprint arXiv:2309.07175

We would like to acknowledge all contributors and collaborators who have supported the development and testing of MELAGE.

🚀 Releases

Stable releases and updates of MELAGE are available on the GitHub Releases page.
- 🟢 Stable releases: Fully tested, recommended for production and research use.
- 🧪 Pre-releases / beta versions: For testing new features and providing feedback.

Stay updated by watching the repository for new release notifications.